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FOREWORD 

This Indian Standard was adopted by the Bureau of Indian Standards, afler the draft finalized by the Programming 
Languages Sectional Committee had been approved by the Electronics and Telecommunication Divisio . Council. 

The object of this standard is to guide programmers to produce good quality programs which are highly readable, 
easy to understand and maintain. 

The advantages in adopting a uniform agreed-on programming style throughout the organization are several. First- 
it ensures that code of a uniform qualit> is produced, it is much more readable, comprehensible and hence, easily 
maintainable. It also enhances protability of the sourcecode. Further, il helps make programs the properly of the 
organization instead of the property of a single programmer. Therefore, here we present several program coding 
guidelines for the progranrming language pascal. 
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1 SCOPE 

This standard lays down guidelines for pascal program 
coding, 

2 REFERENCES 

The following Indian Standard is a necessary' adjunct 
to this standard: 

IS No. Title 

IS 1885 Electrotechnical voca- 

(Part 52/Sec 15) : 1986 bular>^ : Part 52 Data 

processing. Seclion 15 
Programming language 

3 TERMINOLOGY 

For the purpose of this standard, the terms and 
definitions given in IS 1885 (Part 52/Sec 15) : 19K6 
shall apply. 

4 GENERAL 

4.1 Computer programs are used by both machines 
and people, a fact that is too often overlooked. See 
the following two program segments: 

Program Segment 1 : 

a : =0; i : = 1: 97 : ift [i] - k then 
goto 98; if i > -= tsz then goto 99: 
i : = i + 1: goto 97; 98 : a : - 1; 99: 

Program Segment 2: 

found : ^ false; 

i : - 0; 

while ( i < table-size ) and ( not found ) do begin 

i : - 1 + 1; 

if table [i J == key 

then found : == true; 
end; 

4. LI From the computer's view point these two 
fragments behave identically and, given the same input 
data, would produce the same results. However for 
a person tr>ang to understand the purpose of these 
code segments, they are hardly identical*, the first 
example would certainly be considered more difficult 
to read and understand. Although this example is an 
extreme case, it illustrates the importance, to people, 
of using pleasing, helpful and effective coding style. 



4.2 The advantages in adopting a uniform agreed-on 
programming st> le throughout the organization are 
several. First, it ensures that code of a uniform quality 
is produced, it is much nrore readable, comprehensible 
and hence, easily maintainable. It also enhances 
protabilily of the sourcecode. Further, it helps make 
programs the propert>^ of the organization instead of 
the property of a single progranmier. One arguments 
generally given against standards in programming is 
that programming style is a matter of personal opinion 
and preference and thus should not be restricted. This 
argument simply says that chaos is better than order. 

5 COMMENTS 

5.1 Prologue Comments 

5.1.1 (juLcle lines 

E\ery program or every compilation unit of the 
program (module) must have a preface of prologue 
comment at the beginning. It should contain the 
following information: 

a) A brief description of what the program 
module does; 

b) Name of the programmer; 

c) Date written; 

d) A reference to the written technical and 
user documentation manuals, if any. that 
gi\c additional information about this 
program/module; and 

e) Modifications log — purpose, author and 
date of all modifications made of the 

program. 

E\ ciy procedure and function in the program/module 
should also ha\e a prologue comment gi^ing 
the following details: 

a) A brief description of what the procedure/ 
function does. 

b) The entr> conditions — the initial state 
of the subprogram and what initial values 
are passed to it, and 

c) The e.xit conditions — What values are 
returned on completion and whether the 
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stage of the program has changed in any 
other way that is the side-effects caused 
on the global variables accessed by the 
subprogram. 

The prologue comments should be enclosed in a box 
of details ( -' ) or asterisks ( "*' ) in order to clearly 
highlights and distinguish them from the code. 

For example, at the following two programs and 
procedure prologue comments: 

Programme statistics (input, output); 

This program inputs test scores and procedure as output 
the mean, the mode, the lowest and the highest scores, 
the number of valid and invalid scores, and a liistogram 
of all scores. 



author 
date 



H. L. Agarwal 
13 May, 1986 



Procedure sort (var list) 

first element 
last element 
var success 



array-type: 

array-index-t>'pe: 

array-index-t)pe: 



This procedure sorts a list of integers into descending 

order using a process called selection sort. 

List — the array of integer to be sorted. 

First element — the index of last element to be 
sorted. 

Last elem.ent — the index of first element to be 
sorted . 

Exit-conditions : 

Success — true if sort was successful: false 

otherwise 

list — if success is true, then the list is 

returned in sorted order. 



5.1.2 Explanations 

Prologue comments are of great help when one is 
try^ing to understand the purpose or function of an> 
program unit, especially when it has been written b> 
some one else. 

Programs become much easier to maintain if all the 
iitformation mentioned above is specified with every 
program unit. 



Type 



Var 



5.2 DecEaration Comments 

5.2.1 Guidelines 

Closely related to the prologue comments are 
comments explaining each individual item in either 
a CONST or VAR declaration. For ever\' constant or 
variable declared, a brief comment should be included 
there, stating what it is meant for. A good way is to 
declare only one identifier on one line and include 
the corresponding comments on the right side of the 
same line as given below: 

Const 

HIGH - 999 (highest vahd flight number) 
LOW = 1 (lowest valid flight number) 
MAX = 1 ()()() (the maximum length of flight 
tables) 

flight-rauge-type = Low. ..High: 
list-type = array (1... Max)offlight- 

range-t>^pe: 

available: integer: (number of seats available 
on this flight) 

flights: list=t>pe : (list of all flight numbers 
a going in or out today) 

found: boolean: (Switch indicating whether 
flight was found) 

i : integer: (loop index) 

j : integer: (loop index) 

key : flighl-range-type: (night No. to search) 

To make the declaration section even easier to use. 
it is good practice to alphabetise the names in CONST 
TYPE and VAR declarations. 

5.2.2 Explanations 

If the declaration section has been commented in the 
abo\'e fashion, the purpose of any variable can be 
determined easily refering to the VAR declaration 
(always in a fixed and known position) and reading 
the comment about the variable. 

Alphabetising the list can significantly reduce the time 
needed to locate a specific declaration and its 
comment. 

5.3 Paragraph Comments 

5.3.1 Guidelines 

A ver>' u§enii set of comments are those that help 
paragraphing the program that is identifying and 



introducing blocks of code that perform a single task. 
Such comments should explain the purpose of the 
upcoming segment and mark the beginning and 
end of the individual segments, for example, see the 
following code: 

(data input section) 
n : = 0; 
while not eoln do 

begin 

n : -n+ 1; 

read ( string [n] ); 

end; 

read (ch); 

(guarantee that character just read is alphabetic) 
if chinCa' z') 

then begin 

(count frequency of character in input text) 

count : = 0; 

for i : = 1 to n do 

if ch = string (i) 

then count : = count + 1 

writeln ('input character ^ \ ch): 

writeln (frequency count = \ count): 

end 

else writeln ('ERROR : Character must be 
alphabetic:');; 

A test of such commenting is that a programmer should 
be able to read only the paragraph comment and 
understand what the program is doing. 

Notice that all paragraph comments should be 
preceded by a blank line so that they are easier to 
read. They should also be indented by the same amount 
as the code they refer to. 

5.3.2 Explanations 

Presence of paragraph comments in the code makes 
it very simple for the reader of the program to 
understand its logic of functioning. Programs become 
highly readable and hence easily maintainable. 

5.4 Explanatory Comments 

5,4.1 Guidelines 

Sometimes the purpose of some individual statements 
in the code may not be immediately obvious. For all 
such statements a comment can be ver}^ useful, for 
example, if we were searching for a match between 
a string of length within some text of length n ( m 
= n ), the last possible start position for such a 
match (assuming the array was indexed from 1 ) would 
be the subscript n - m + 1. However, to the first time 
reader the reason for the upper limit in this loop 
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construct 

for I := I to (n - m + I) do 

would probably not be immediately clear. It would 
be much belter to say: 

(position n - m + I is the last possible place 
a successful match can start) 

for i : ^ 1 to (n - m + I) do 



Explanatory^ comments should not be used to restate 
the obvious intent of the Paseal statements, for 
example, the following are worthless comments: 

num : ~ num + I: (increment num) 

read (day, month, year): (input the date) 
We should also avoid unclear, technical, and jargon- 
filled comments, for example: 

(check the two link fields in the doubly linked 
list to sec if they arc pointing to the same node 
element) 

if head ^ ^ tair 

then 

Instead, how much nicer it is to say: 

(determine if we have come to the end of list) 

if head'^ - tair 

then 

Comments should always describe the purpose and 
not the operation of the statements. 

5.4.2 Explanations 

Explanator> comments make it easy for the reader 
to understand the portions of code whose purpose is 
not obvious by simply reading them. Hence they make 
programs ver\ readable and maintainable. 

5.5 Matchinji-Pair Comments 

5.5.1 (fuiclelines 

These are another very useful class of comments that 
help identifying matching pairs of reserved words 
especially the BEGlNs and END's of nested loops 
or large compound statements. It is ver\' common to 
see a number of compound statements (Within loops 
or conditionals) end near one another. 

All such ends should be followed by a brief comment 
pointing to their corresponding begins as in the 
following: 

end (of inner while loop) 

end (of else clause for negative parameters) 



end: (of procedure read file) 
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5.5.2 Explanations 

Although the indent^ition will give us a clue, a comment 
attached to each END can also help us in identifying 
the matching BEGIN-END or CASE-END pairs, and 
hence help traching the programs control flow, 

5.6 Directory Comments 

5.6.1 Guidelines 

In case of very large programs, it is worthwhile to 
provide an alphabetized directory or table of procedure 
and functions in the program in a comment form at 
the beginning of the program. It should include the 
name of each procedure and function and the location 
(line No.) where it is declared. 

Some compilers provide facilities to output cross 
reference tables for jiIl identifiers used in the program. 
If such facilities are available, then these director) 
comments may be omitted and the cross-reference 
table should be generated and included with the final 
program code listings. 

5.6.2 Explanations 

In large programs with hundreds of procedures and 
functions, if directory comments are included then 
it becomes ver>^ easy for the reader to locate any 
particular procedure/function quickly. 

5.7 Comments on Writing Comments 

Comments should always be written along with the 
code, as it is being developed, not after. If comments 
are inserted later, what will probably result is a grossly 
under commented program, with ver\^ brief comments 
that are only marginally helpful. Also, if there is a 
significant time lapse between writing a program and 
commenting it, the comments may be inappropriate 
and less detailed than they would have been if we 
had written them immediately. 

One excuse normally offered for not writing comments 
initially along with the code is that, the program 
specifications are usually in a state of flux, and so 
the code is subject to frequent changes in the beginning: 
and if one has to modify comments everytime. he 
modifies the code, it leads to 'unnecessary'' wastage 
of time. Such excuses are rather lame, because in 
surprisingly short periods of time even the original 
programmers tend to forget many of the program 
details, and later when in the absence of any comments, 
they have to spend long durations of time tracing their 
program logic while modifying or debugging their 
program, all the original time 'saved' is used up many 
time over. So even of some more time to used up in 



modifying comments while modifying code, one 
should not worn about it. 

Finally after all the comments are written, our job is 
still not finished. As we perforin the job of program 
maintenance, it is critical that we modify' the comments 
to reflect the new intent of any modified code. 
Programmer rely heavily on conunents to explain what 
is going on. Incorrect or outdated comments could 
thus be ruinous to a proper understanding of the 
program, for example, if we say: 

( Here we compute the median score all who completed 
the test ) 

but then later rewrite the code to calculate the 
arithmetic mean, we could completely mislead 
sou^eone who is trying to understand what the 
program does. Incorrect or misleading comments are 
much worse than no comments at all. 

6 BLANK LINES 

6.1 Guidelines 

Finally after all the comments are written, our job is 
still not finished. As we perforin the job of program 
maintenance, it is critical that we modify^ the comments 
to reflect the new^ intent of any modified code. 
Programmers rely heavily on comments to explain 
what is going on. Incorrect or outdated comments 
could thus be ruinous to a proper understaiiding of 
the program, for example, if we sav:' 

( Here we compute the median score of all who 
completed the test ) 

but then later rewrite the code to calculate the 
arithmetic mean, we could completely mislead 
someone who is tr>'iug to understand what the program 
does. Incorrect or misleading comments are much 
worse than no comments at all. 

7 LAYOUT, INDENTATION AND 
EORMATTING 

7.1 Guidelines 

Using blank lines is an often overlooked method of 
improving the program code appearance. Just as blank 
linesare used in English to separate paragraphs, they 
can be used to separate the various program elements. 

A single blank line should Ije left before every logically 
distinct group of statements within a subprogram 
or program, for example, see the following code 
sej^ment; 

read (x. y. z): 
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read (theta); 

first : =sqr (x) + theta; 

second : = sqr (y) + theta; 
third : =sqr (z) + theta; 

writeln; 

writeln (first, second, third): 

About two or three blank lines should also be left 
before every subprogram declaration and before 
the beginning of the main program. 

One blank line should be left before CONST, TYPE, 
VAR declaration sections. 

A blank line should be left before every comments, 
to make it prominent. 

7,1.1 Explanations 

Proper use of blank lines in the program code improves 
the code appearance and enhances its readability:. 

7.2 Blank Spaces 

7.2.1 Guidelines 

Use of blank spaces is often optional at many places 
in the language syntex. Yet, blanks should be left in 
all places that would improve the readability of the 
code. 

One blank space should always be left before and after 
the arithmetic operators (+, -, : = etc) and logical 
operators (>, <,<=,> =, <>, =). 

A space should also be left after every comma: and 
before and after separators like colon :' equal, etc. 

Ablank should also be left after ("** or {' and before 
'*') or '}' comment delimitors. 

Blank spaces can be used to reflect operators 
precedence in expressions. Thus, one should use, for 
example, 

1 + a*b (better way) 

and not 

1 + a * b (misleading) 

7.2.2 Explanations 

Just as blank lines, blank spaces also improve the code 
appearance and enhance its readabilit>', 

7.3 Parentheses 

7.3,1 Guidelines 

Since mathematical and logical operations are 



governed by the operators precedence and order of 
use. programmers can quite often get through with 
few parenthesis, but this situation makes reading and 
correcting programs very difficult. The following 
examples illustrate this: 

(Bad Way) (Good Way) 

k - a div 2 k ~ (a div 2) 

a/b + c/d + e/f (a^) + (c/d) + (e/f) 

k > y or q (k > y) or q 

a + b<c (a + b)<c 

A basic rule is: whenever in doubt, use parentheses, 
not only to improve readability, but to prevent errors. 

However, commonsen^e should be used to avoid using 
so many parentheses that is confusing instead of 
clarifying, for example, 

((((aA» + (c/d)) + ((e/f))) 

A single expression of extreme complexit}^ with many 
adjacent parentheses should be broken into several 
separate statements for clarity. 

7.3.2 Explanations 

When properly used, parentheses greatly improves 
the readability of expressions used in the program. 
They help removing the conftision in the reader "s mind 
which could otherwise arise regarding the various 
operator precedences. 

Programmers often under parentheses in logical 
expressions with the result that the program is 
incorrect. 

7.4 One Statement per Line 

7.4,1 Guidelines 

Although Pascal allows several statements on one 
line, it is usually a bad practice to use multiple 
statements on one line, it makes the program ven 
difficult to read. A better approach is to place only 
one statement on each line, for example, look at the 
following two places of code: 



(bad way) 

a : = 14.2: for i 

k: = i * k: 

y (i) : = k; end: 

(good way) 
a: = 14.2: 

for i : - I to 10 do 

begin 

k : = 1 * k: 

y (i) : = k: 

End: 



= 1 to 10 do begin ^ (i) : = 0: 
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7.4.2 Explanation 

Using only one statement per line makes the code 
look very neat and hence improves its readability 
significantly. 

Syntex error messages from the compiler usually 
indicates the line number so if only one statement 
is on one line, it also becomes easier to locate the 
syntex error. 

7.5 Splitting Expressions 

7.5.1 Guidelines 

If an arithmetic expression statement does not fit on 
one line, and has to be split over two lines, it should 
be split after an operator, for example: 

(careless form) 

a; -= b - c 

- (d + 2); 

(better form) 

a: = b - c - 

(d + 2); 
Further the second line should always be indented to 
the right of Iheassignment operator on the previous 
line. 

Similarly, if a procedure or function call cannot be 
accommodated on one line, the parameter list should 
be applied after a comma ',' and the successive line 
shouldbe indented to the right of opening parentheses 
'C on the previous line. 

7.5.2 Explanations 

Splitting statements in the above fashion leaves an 
operator or separator character dangling on the first 
line which will immediately indicate to the reader 
that the statement is to be continued on the next line. 

7.6 Columnarization 

7.6,1 Guidelines 

One should always tr>^ to line up all the =' signs in 
CONST and TYPE declarations, and \^ signs in VAR 
declarations, for example: 



Const: 










STOP - MAX 


= 100; 






BUS - MAX 


= 25: 






Q-MAX 


= 75: 




Type: 








Stop 


- number-type 


= 0, 


, STOP-MAX 


bus 


- number-tj'pe 


= 0, 


, BUS-MAX 


q 


- length-t>pe 


= 0. 


, Q-MAX 



Var 

Sqeue: array [ stop-nuniber4ype] of q-length-type; 
bus : bus-number-type; 

Similarly, one should also try to columnarize the : 
= signs in a sequence of arithmetic assignment 
statements, for example, 

a : = b + c: 
sign : == base * count: 
cost : = pay * bonus; 

7.6,2 Explanations 

Columnarization greatly improves the neatness and 
readability of the program. It makes the code look 
pleasing to the eye. 

7.7 Indentation of Control Structures 

7.7.1 Guidelines 

Statements should be indented to indicate that they 
belong together. Look at the following two segments 
of code: 

(with no indentation, not readable at all) 
if i < 1 then 
factorial : = 1 else 
begin factorial : = 1: 
for j : - 2 to 1 do 
factorial : = factorial * j 
end: 
( with proper idenlation. highly readable) 



if i < 1 



then factorial : = I 

else begin 

factorial : = factorial * j: 

for j : = 2 to i do 

factorial : = factorial * j: 



end: 



Here we suggest indentation layouts for various pascal 
control structures. 

A general rule is that for ever>^ successive level of 
indentation, indent three spaces to the right, and indent 
all statements at the same level by same amount. 

In the following discussion, SL S2 SN are 

statements (possibly compound), b is a boolean 
expression, is a scalar variable, and expr 1 and expr 
2 are scalar expressions. 

i) Layout for compound statements: 

begin 
SI: 



S2; 
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SN; 
end 
li) Lavtout for IF statement: 
ifb 

then SI; 
else S2; 

if SI and S2 are compound statements use the 
following layout: 

ifb 
then begin 
SI; 

S2; 



SN; 
end 
else begin 
SI; 
S2; 



SN: 



end: 



iii) Layout for WHILE STATEMENT: 
While b do 
Si; 
if SI is compound use while b do 
begin 
SI; 
S2: 



SN; 
end: 
iv) Layout for REPEAT statement: 
repeat 
SI: 



SN: 
until b; 
v) Layout for FOR statement: 
for i : = exprl to expr2 do 
SI: 
if SI is compound then 
for i : - exprl to expr2 do 
begin 
SI; 
S2: 



SN: 
end: 

vi) Layout for CASE statement : (C is case selector 
and ais are case lables) 

case c of 
al : SI 

a2 : S2: 



aN : SN: 
end: 

vii) Layout for WITH statement (v is a record 
identifier) 
with V dc 
begin 
SI: 



SN 
end: 

7.7.2 Explanation 

Proper identalion greath improves the readability of 
the program. It reflects the logical structure of the 
program and makes it look pleasing to the eye. It is 
of great help when one is tning to trace the program/s 
control flow. 

7.8 Indentation of Data Structures 

7.8.1 Guidelines 

Besides showing program stmcture, indentation should 
also be used to show data structures wherever possible: 
for example, see the following record declarations. 

Student ; record 

name : array [1..25] of char; 

address: record 

street: street type; 
city : city type: 
state : state type: 

end: 

age : integer: 

end: 

7.8.2 Explanations 

Just as in case of control structures, indentation in 
record declarations also reflects the structure and 
nesting of the data elements involved. 
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7.9 Indentation of Nested Subprograms 

7*9.1 Guidelines 

Pascal allows declaration of procedures and functions 
within other procedures or functions. However, it is 
recommended that nesting of procedures and functions 
should be avoided as the programs do not necessarily 
become more readable if this is done. Still, if such 
nesting is used, subprograms should be appropriately 
intended to show their scope and structure. 
Subprograms should never be nested more than one 
level deep. 

The following example shows indentation of 
procedures nested one level deep: 

procedure a: 

procedure b; 
begin 



end; (of b) 
procedure c; 
begin 



end; (of c) 
begin (of a) 



end; ( of a) 
7.9,2 Explanations 

Indentation of nested subprograms helps indicating 
their scope and hence enhances the progranrs 
readability. 

7,10 Automatic Indentation 

Most programming environments provide certain 
programs that format Pascal program automatically 
Programmers who write programs with good 
intelligible layouts do not need to use such formatting 
programs. Others may feel that counting blanks is 
something that the computer can do better than they 
can, and they would prefer to use formatting programs. 
People working together on a project, should initially 
decide whether or not to use a formatter, and 
then everyone should stick to the decision. 

However, there are atleast two good reasons for using 
a formatter, even if one is justifiably proud of this 
on layouts. First, automatically formatted programs 
would always be consistent in layout. Second, although 



entering a new program neatly is not difficult, revising 
a program while preser\/ingthe layout can be extremely 

tedious, 

8 IDENTEFIER NAMES AND THEIR 
DECLARATlOnV SCOPE 

8.1 Choosing Meaningful Names 

8.1,1 Guidelines 

Identifier names should always be selected to 
best identify the symbolic quantity or thing they 
respresent. Look at the following two statements: 



m : = s / (n - b); 
average : = sum / (count 



invalid) 



The former gives no clue to the purpose of the 
operations we are performing whereas the latter is 
quite clear even when presented out of context. 

Since Pascal places no restrictions on identifier 
lengths, names as long as necessary should be used. 
However, it should be tried that all identifiers are 
unique within the first fifteen characters. 

Visually similar names and confusing characters ( for 
example, A x 10 and A x 10 ) should be avoided. 

8.1.2 Explanations 

Nothing contributes as much to a program's clarity 
and readability as does the selection of good nemonic 
names. Unwise choice of variable or procedure names 
jcan render an otherwise clear program nearly 
incomprehensible. 

8.2 Delimit Words in Indentifiers 

Although standard Pascal does not allow use of any 
special characters in indentifiers, most 
implementations allow some deliniitors like 
underscore (.), etc. to be used in identifiers. It is a 
good idea to use delimitors to separate all the words 
in an identifier, for example: 

recoil should be re-coil 
identrx^ should be id-entr>^ 
crafter should cr-after 

If the complier does not allow use of any delimitor 
character within identifiers then mixed case letters 
should be used to delimit words, for example, the 
first letter of each word should be in uppercase, for 
example: 

ReCoil 
IdEntr)' 
CrAfler 
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8.2.1 Explanations 

Separators make the names more readable and less 
susceptible to other interpretations. 

8.3 Preserve Identifier Meanings 

8.3.1 Guidelines 

One variable should never be used for multiple 
purposes, for example, it should never be used to 
denote different things at different points of time in 
the program. 

Similarly, identifiers declared in outer-blocks, should 
not be redeclared in inner-blocks as local variables/ 
constants. However, this rule does not apply to 
variables used as general purpose array indices, loop 
counters, for example, i, j, etc. In subprogram 
declarations, as far as possible, formal parameter 
should be given the same names as that of actual 
parameters used in calls. 

8.3.2 Justification 

Many programmers use one variable to denote different 
things at different points of time in the program. The 
rationale given is memory efficiency. But there are 
several things wrong in this practice. First, since each 
identifier in the program should be given a descriptive 
name that suggests its purpose, this is not possible 
if the same identifier is used for multiple purposes. 
Second, using an identifier for multiple purposes is 
a dangerous practice, because it makes the program 
code very sensitive to later modifications. 

Redefinitions of identifiers in inner blocks cause 
confusion and hamper readability. 

8.4 Project-Wide Standard AbbreviatilW^ 

8.4.1 Guidelines 

When working on a large project, each programming 
manager should fiud it advantageous to develop a list 
of standard abbreviations pertirient to the applications. 
And then everyone in the team should use only those 
abbreviations and not their own variations in their 
programs. In absence of standard abbreviations, 
different programmers would use different codes to 
mean the name things, for example, different people 
could use mstr, mast mst, etc, to abbreviate master 
leading to confusion. 

8.4.2 Explanations 

Use of standard abbreviations ensures consistency 
among all programs over the project, and is veiy helpflil 
when programs written by one person are read by others 
in the team. 



8.5 Use of Standard Prefixes or Suffixes to 
Indentifiers 

8.5.1 Guidelines 

When working with several files, it is often a good 
idea to use a standard prefix to the file name, its 
corresponding record name and to all the fields of 
that record, for example, in the example below, MST 
is used as a prefix for the Master file: 

mst -student-record : record 

mst-name : name-type: 
mst-address : address-t>^pe: 
mst-number : number-type; 
end: 
mst-sludent-file : file of mst-student-record; 

It is also helpful to use a suffix - "type' to all type 
identifiers, for example, 

counter-type = 1.. max-lines 
page-index-type= l..max-on-page; 
word-type = packed array (word-type) or 

char; 

8.5.2 Explanations 

If each file as a unique prefix, it helps locating the 
field in the program listing. When there are several 
records being used in a program, and especially nested 
ones, then it is often convenient to use 

with record 1. record 2, do 

begin 



end: 

type of construct to aviod writing very long field 
qualifiers. In such situations the use of standard 
prefixes to field names is of great help in identifying 
fields with their corresponding records. 

It also removes confusion when identical field names 
are used in different records, for example; 



mst-date 

trn-date 

rcc-date 



(master date) 
(transaction date) 
(record date) 



Even though three date fields are used each one is 
easy to identifS^ because of the prefix. 

8.6 Distinguish Variables from Constants 

8.6.1 Guidelines 

All constants declared in the program should always 
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be written in upper case letters and all other identifiers 
like variables, types, procedure and function names, 
etc, should be written in lower case letters. 

8.6.2 Jusiification 

Using different case letters for constants and variables 
is of great help while reading large programs with 
hundreds of variables and constants. The appearance 
of the identifier itself, in any expression, indicates 
whether it is a variable or constant. 

8.7 Project-Wide Standard Include Files 

8.7.1 Guidelines 

In case of large projects, all programmers should use 
a project wide standard set of constants, types,variable 
declarations that are common to several programs 
in the project. The project leaders should identify 
these common sets of declarations and write them 
in separate source-files, which should then be directly 
included in all the programs requiring them. Most 
compilers provide such including of copying 
facilities, for example, VAX 11 Pascal compiler 
provides % INCLUDE facility to include other files 
in the source code. 

The names defined in these project-wide include-files 
becomes, in effect, reserved words for that project. 
Even if a programmer does not need them in some 
program, he or she should not use those names to 
declare other things, because later modifications to 
the program might require their use. 

8.7.2 Explanation 

Use of project-wide standard INCLUDE files ensures 
consistency in declaration of identifiers common to 
several programs in the project. 

It also helps when the declaration for any such common 
identifier needs to be modified. Only the INCLUDE 
file would need to be modified instead of modifsing 
all individual programs using that identifier 

Also, different versions of a project can ha\e different 
include environments, thus saving the trouble of 
modifying declarations in all programs. 

8.8 Scpjie of Declarations 

8.8.1 Guidelines 

Constants should always have global scope. 

Types should also have global scope in most cases. 

Variables should be declared according to their usage. 



Variables local to a subprogram should be declared 
locally { for example, nested ) but the program does 
not necessarily becomes more readable if this is done. 

8.8.2 Explanations 

It is easier to locate a constant or type identifier 
ifthcre is one constant and type declarations section 
at the beginning of the program than if the> are declared 
in e\'er\ subprogram. 

Declarations of local variables within the 
subprograms they are used in is of great help from 
program maintenance point of view. 

9 CONTROL STRUCTURES AND 
SUBPROGRAMS 

9.1 Multiple Choice fi^ranching 

9.1.1 Guidelines 

CASE statement should be used for multiple choice 
branching instead of a series of IF-THEN statements. 
IF should be used for multiple choice constructs only 
when the conditions are not mutually exclusive, when 
their order of evaluation is important or when different 
\ariables ha\ e to be tested together. 

9.1.2 Explanations 

Although the IF statement could always be used instead 
of CASE, use of CASE greatly enhances the readabilit>. 

9.2 Avoidin<; Thcn-If Constructs 

9.2.1 Guidelines 

A THEN-IF CONSTRUCT IS OF THE FORM: 

IF (n > b) 

then if (x > y) 
then a : = X 
else a : = b 
else a : = b : 

THEN-IF constructs should always be rewritten in 
the more ob\ ious ELSE-IF form, as in the following 
segment: 

ir(a<-b) 

else if ( X > y ) 
then a : = x 
else a : =^ b: 

9.2.2 Explanations 

THEN-IF statements tend to obscure the conditions 
under which various actions are performed. ELSE- 
IF constructs are easier to understand and follow. 
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9.3 Avoiding Repeat-Until Loops 

9.3.1 Guidelines 

The WHILE-DO loop should be used instead of 
REPEAT-UNTIL loop, except where the logic of the 
problem, explicitly requires doing the body of the 
loop atleast once regardless of the loop conditions. 

9.3.2 Explanations 

REPEAT-UNTIL is discouraged because loops should 
be coded in their more natural form and they should 
test their looping conditions before proceeding to 
execute the loop body. 

9.4 Avoiding Goto*s 

9.4.1 Guidelines 

The use of GOTO statement ( and hence labels ) should 
be avoided. Pascal provides all types of structured 
control statements like IF-THEN-ELSE, WHILE-DO. 
FORDO, CASE, etc, with the help of which all types 
of constructs can be easily implemented without using 
GOTO. However, use of GOTO may be considered 
in situations where it considerably improves 
the organization and clarity of the program, it should 
be used when an error or abnormal termination of an 
entire program unit causes sudden break in the normal 
flow of logic. In such a case, the GOTO would usually 
jump to the end of the emire program unit. 

For example, if execution is deeply nested inside a 
set of looping structures and a fatal error is 
encountered, it might be very inconvenient to exit 
from the loops one level at a time using boolean 
variables. It might be better to handle this multilevel 
exit with a single GOTO, as in the following 
fragment, which terminates whenever a negative 
element is encountered in a 3-dimensional array called 
matrix; 

for i : - 1 to DEPTH do 
forj — 1 to WIDTH do 

fork : - 1 to LENGTH do 
if matrix [ i, j, k ] < o 
then goto 99 ( transfer to program end ) 
else sum = sum + matrix [ i. j, k |: 

99 : end: ( of subprogram ) 

Wherever GOTO is used it is a good idea to add a 
comment there, since the label itself does not reflect 
the location of transfer. ( Afterall, the label 99: can 
be anywhere in the program unit ). 

GOTO should never be used a lump backward. By 
definition, a backward jump is a loop and it can always 



be implemented with interactive control structure, 
WHILE, FOR etc. 

In most program units GOTO should not be required, 
but if required not more than one GOTO should be 
used in the program unit. 

9.4.2 Explanations 

The use of GOTO's is highly correlated with errors 
and had-to-rcad code. 

The GOTO is also prohibited for the abstruct reason 
that algorithms should be expressed in structure of 
the underlying reasoning or thinking process. 

9.5 Avoiding Depth Nestings 

9.5.1 Guidelines 

Nesting of programs constructs to depths greater than 
three or four levels should be avoided. Procedure 
calls should be used to avoid excessive nesting. 

Explanations: 

If the nesting becomes too deep, as in 

While Bl do 
if B2 

then while B3 do 
if B4 then SI 
else S2 

it becomes extremely difficult to determine the 
coditions under which statements like S2 above, will 
be executed. The clarity of the code is obscured. 

Excessive nesting is also an indication of fuzzy thinking 
and poor design; 

9.6 Subpi*«};ram Arguments 

9.6.1 (Tihdelines 

Tlic preferred method for inter-stibprogram 
communication should always be passing of 
arguments or parameters as against the use of global 
variables. However, the program should be so 
decomposed into subprogram that both the parameters 
as well as global variables used in individual 
subprograms are few in number. 

A good rule is to use Twq as an upper bound on the 
number of parameters to a subprogram. 

Global variables should be used only on a highly 
selective and needed basis. Any side effects caused 
on them by tlie subprogram invocations should be 
clearly indicated and highlighted through appropriate 
comments. 



11 



IS 14430 : 1997 
9.6.2 Explanation 

Long and involved parameter lists result in excessively 
complex subprograms that are difficult to understand. 
and difficult to use. 

If too many global variables are used in procedures 
or functions, then future modifications in the programs 
become extremely difficult to make. 

9.7 Restrictions on Subprogram Size 

9.7.1 Guidelines 

It is very important that all programs should be so 
designed that most of the procedures or functions 
used are smaller than 30-40 lines of source-code and 
in no case should they exceed one page of computer 
printout. 

This, of course does not mean that one should 
artificially split on otherwise cohesive code into 
places, just to satisfy the above criteria. 

Top-down design, that is, development b\ step-wise 
refinement of the problem is very helpful in 
modularizing the programs. 

9.7.2 Explanations 

Algorithms are easier to create and to understand if 
they are built with places small enough to be grasped 
as one concept. They also become easier to maintain 
if all subprogram units are small in size. 

9.8 Project-Wide Standard Libraries 

9.8.1 Guidelines 

General purpose procedures or functions thai are 
called by more than one program in a project, should 
be placed in separate source files, compiled 
and maintained as library procedures or functions. 
There should not be too many libraries floating around, 
but the object codes of all the general purpose 
subprograms should be pooled into one central 
library which should then be accessible to everyone 
in the team. 

9.8.2 Explanations 

Use of project-wide standard libraries ensures 
consistency in the use of primitive general purpose 
procedures/functions over the project. Their use also 
reduces development time which would otherwise be 
spent by several persons developing them for use in 
their respective programs. 

10 OTHER STANDARDS 



10.1 No Hard-Coding 

10.1,1 Guidelines 

Constants should always be given symbolic names 
and declared in the CONST declaration section. Inside 
the program code they should be referred only those 
symbolic names and not be their actual values, for 
example, when defining array bounds or while 
traA ersing an array using a FOR loop, the symbolic 
name of the last index value of the array should be 
used, for example: 

(bad programming) 
If index < 100 

then 

(good programming) 
CONST SIZE- 100: 



If (index < SIZE) 
then .... 

Similarly, when using any codes, symbolic names of 
the codes should be used in the program and the actual 
codes should be declared in the CONST declarations. 

A good rule is that program should not contain an> 
literals other than and 1 outside the CONST 
declaration section. Literal strings, however, maybe 
used in write statements. 

10.1.2 Explanations 

Constants that are hard-coded (otherwise known as 
'magic numbers* because they mysteriously appear 
with no explanations) are hard to locate when 
modifying the programs. Furthermore, instances of 
constant minus one" or 'constant plus one" for 
example, are even more elusive to the reader or 
the maintenance programmer. 

Use of symbolic constants also helps building 
generality into the program. 

10.2 Avoiding Non-portable Compiler Features 

10.2.1 Guidelines 

Different compilers provide different extensions over 
and above the standard features supported by the 
language. Use of these extensions provided by the 
compiler should be restricted. If it is inevitable to 
use them, all the environment-specific-features 
dependent code should be localised and segregated 
from the other code. 
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However, it may be noted that, although use of 
underscore in identifier names, using faciht>^ to include 
other files in the source-code file, etc, are non-standard 
features provided by most compilers, their use is not 
discouraged, as the benefits accrued by their use far 
outweigh the effort required in modifying the code 
while porting it to a new system. 

10.2.2 Explanations 

Avoiding the use of non-standard features provided 
by the compiler minimizes the effort required when 
the software has to be ported to a new system/ 
environment. 

10.3 Code Reviews 

In some disciplines like Engineering Drawing, a 
supervisor usually signs the drawings when he or she 
agrees that they look nice and conform to the company 
or professional standards. Unfortunately we do not 
often have any such requirements in programming. 
Clarity and style are almost always ignored; everyone 
wants to know if the program works, and, if not, when 
it will. 

It should be worthwhile to have non-trivial programs 
bear signatures of two people other than its author. 
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who certify that the program is reasonable in style 
and format. This small requirements by a programming 
manager would result in better designed programs at 
almost no cost. It would make the programmers much 
more conscious of style and clarity because of the 
knowledge that two people would be reviewing his 
or her programs. 

Also, there is a class of bugs known as blind spots 
wliich will nc\Qr be found by the author of the program. 
If there is a procedure that every program is reviewed 
by someone other than its author, such bugs could 
be detected early and save the embarassment to the 
author when these bugs surface later. 

11 CONCLUSION 

It should be clear to every programmer that a small 
extra effort needed in the beginning to make 
programming readable is minimal in comparison 
to the cost of revising, locating errors in, or modifying 
an abstruse program. 

Programs have tendency to stay around longer than 
planned and grow in use for beyond the original plan, 
so it seems worthwhile to write a good program right 
in the beginning and save trouble later. 
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